home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PRINTER / DS2.ARJ / SP2INTFC.DOC < prev    next >
Text File  |  1991-07-27  |  10KB  |  215 lines
  1. This document describes the programming interface capabilities of DISK SPOOL
  2. II version 4.00.  Please note the following definitions:
  3.  
  4. ASCIIZ  -  This refers to a file spec (including drive and path) followed
  5.            by a binary 0.  The maximum length of the entire ASCIIZ
  6.            (including the terminating 0) is 33 bytes.
  7.  
  8. port involved - This refers to the Spool Port  (i.e. - the port that DISK
  9.                 Spool II is intercepting and re-routing to disk).
  10.  
  11.                         1 - COM1
  12.                         2 - COM2
  13.                         5 - LPT1
  14.                         6 - LPT2
  15.  
  16.                 The reason that the "port involved" needs to be indicated
  17.                 in most of the function calls described below is that it
  18.                 is possible to load 2 or more copies of DISK SPOOL II into
  19.                 memory at the same time, thereby driving multiple printing
  20.                 devices simultaneously.
  21.  
  22.  
  23. Note that all program hooks are done via software interrupt calls.  The
  24. interrupt number used is INT 1Ah.  Thus, the program must first set AH as
  25. well as the other registers as indicated, and then do an INT 1Ah.
  26. -------------------------------------------------------------------------------
  27.  
  28. 1. Enable the Spooling Function.
  29.  
  30.    Input:
  31.                 ah = 0e0h
  32.                 al = 1
  33.                 cl = port involved
  34.    Return:
  35.                 ah = 0 ... if successful
  36.                      0f0h  if request failed because there is no copy of
  37.                            DISK SPOOL II in memory that is spooing the
  38.                            designated port.
  39.                      0ffh  if request failed for a miscellaneous reason
  40.  
  41. 2. Disable the Spooling Function.
  42.  
  43.    Same as 1, above, except that al = 2 on input.
  44.  
  45. 3. Enable the Despooling Function
  46.  
  47.    Same as 1, above, except that al = 3 on input.
  48.  
  49. 4. Disable the Despooling Function
  50.  
  51.    Same as 1, above, except that al = 4.
  52.  
  53. 5. DISK SPOOL II status call.
  54.  
  55.    Input:
  56.                 ah = 0e1h
  57.                 cl = port involved
  58.    Return:
  59.                 ah = 0f0h ... no copy of DISK SPOOL II is currently in memory
  60.                               that is spooling the designated port.
  61.                      0 ...... a copy of DISK SPOOL II is installed for the
  62.                               designated port; and furthermore:
  63.  
  64.                 ES:BX  ...... a far pointer to an ASCIIZ of the current
  65.                               Spool File (or in the case where the AutoSpool
  66.                               or the AutoDespool feature is enabled, an ASCIIZ
  67.                               of the next spool file.)
  68.                 ES:SI  ...... a far pointer to an ASCIIZ of the current
  69.                               Despool file ... i.e. - the file currently being
  70.                               printed.
  71.                 cl = 0 ...... if the Despooler is disabled.
  72.                      41h .... if the Despooler is enabled.
  73.                 ch = 0 ...... if the Spooler is disabled.
  74.                      41h .... if the Spooler is enabled.
  75.                 dl = 0 ...... if the Despooler is standing by.
  76.                      41h .... if the Despooler is currently printing.
  77.                 ES:DI  ...... a far pointer to the 3-byte file extention
  78.                               being used by DISK SPOOL II.  (e.g. - SPL)
  79.  
  80. 6. Get 1st spool file.  Based on the user-designated spool file directory,
  81.    and the user-designated file extention, this function returns the ASCIIZ
  82.    of the first file that exists.  NOTE: this function is only meaningful if
  83.    the AutoSpool or AutoDespool functions are enabled.
  84.  
  85.    Input:
  86.                 ah = 0e2h
  87.                 al = 1
  88.                 cl = port involved
  89.  
  90.    Return:
  91.                 ah = 0f0h if no files exist
  92.                    = 0ffh if function call failed.
  93.                    = 0 if function succeeded; and furthermore:
  94.                      ES:BX is returned as a far pointer to the ASCIIZ of
  95.                      this first file.
  96.  
  97. 7. Get the next spool file.  This function must always be proceeded by the
  98.    function described just above, "get 1st spool file".
  99.  
  100.    Input:
  101.                 ah = 0e2h
  102.                 al = 2
  103.  
  104.    Return:
  105.                 ah = 0f0h if no more files exist
  106.                    = 0ffh if function failed
  107.                    = 0 if function succeeded; and furthermore:
  108.                      ES:BX is returned as a far pointer to the ASCIIZ of
  109.                      the file.
  110.  
  111. 8. Obtain status about a spool file.  NOTE: this function is generally used
  112.    when AutoSpool or AutoDespool is enabled.
  113.  
  114.    Input:
  115.                 ah = 0e3h
  116.                 al = 1
  117.                 ES:BX points to the ASCIIZ of the file
  118.    Return:
  119.                 ah = 0f0h if the file pointed to was not a DISK SPOOL II
  120.                           spooled file.
  121.                    = 0ffh if the function failed.
  122.                    = 0 if the function succeeded; and furthermore, ES:SI is
  123.                      returned as a far pointer to the following data
  124.                      structure:
  125.  
  126.     Length in Bytes       Description
  127.     ---------------  ----------------------------------------------------------
  128.          1              Hour when file created, or last changed.
  129.          1              Minute when file created, or last changed.
  130.          1              Year when file created, or last changed. 0 = 1980,
  131.                         1 = 1981, and so forth.
  132.          1              Month when file created, or last changed.
  133.          1              Day when file created, or last changed.
  134.          1    *         Number of copies requested to print.
  135.          1              Number of copies already printed.
  136.          1    *         Print port; 1 - COM1; 2 - COM2; 5 - LPT1; 6 - LPT2
  137.          1    *         Save status; 1 - file will be saved after printing;
  138.                         0 - file will be deleted after printing.
  139.          1    *         File status:
  140.                         1 - file finished printing, but being Saved.
  141.                         2 - file held.
  142.                         3 - file queued up for printing.
  143.                         4 - file currently being spooled.
  144.                         5 - file currently being despooled (i.e. - being
  145.                             printed)
  146.          16   *         15-byte description, followed by a binary 0.  DISK
  147.                         SPOOL II generally places the name of the process
  148.                         invoked from DOS into this field.  For example, if
  149.                         Lotus created the spool file, and the command that
  150.                         was used to load Lotus was 123, then the description
  151.                         would be 123.  If SP2PRT is used to spool a previously
  152.                         existing DOS file, then the name of the file is placed
  153.                         into the description.
  154.          2              High order word of the file's size in bytes.
  155.          2              Low order word of the file's size in bytes.
  156.          2              High order word of the number of bytes left to print.
  157.          2              Low order word of the number of bytes left to print.
  158.  
  159. 9. Update a spool file.
  160.  
  161.    Input:
  162.                 ah = 0e3h
  163.                 al = 2
  164.                 ES:BX points to the ASCIIZ of the file to update.
  165.                 ES:SI points to the same data structure as above.  Only the
  166.                 fields marked with an '*' are updated; and the File Status
  167.                 byte may be set to a 2 in order to hold the file, and to a 3
  168.                 in order to release it.
  169.    Return:
  170.                 ah = 0f0h if the file pointed to was not a DISK SPOOL II
  171.                           spooled file.
  172.                      0ffh if the function request failed.
  173.                      0    if the function request succeeded.
  174.  
  175.   NOTE:  The most common way to effect an update to a spool file is to perform
  176.          an "obtain status about a spool file" first (8., above); after which
  177.          point ES:BX and ES:SI are set correctly, and you need only modify
  178.          those fields that you wish to update.  Then issue this function call.
  179.  
  180. 10.  Spool a file.  This function is used when an already existing DOS file
  181.      needs to be printed.
  182.  
  183.    Input:
  184.                 ah = 0e4h
  185.                 al = 1
  186.                 ES:BX points to an ASCIIZ of the file to be spooled.
  187.                 cl = port involved
  188.    Return:
  189.                 ah = 0ffh if function failed.
  190.                    = 0 if function succeeded.
  191.  
  192. -------------------------------------------------------------------------------
  193.  
  194. The following is an example of how the above function calls could be used to
  195. designate the number of copies to be printed.  This example assumes that
  196. the AutoSpool or the AutoDespool function is enabled.
  197.  
  198. 1. Perform a DISK SPOOL II status call (5., above).  ES:BX will be returned
  199.    as a far pointer to an ASCIIZ of the next spool file.  Copy the 33 bytes
  200.    pointed to into your own save area.  NOTE:  Even though the name of
  201.    the next spool file is known, the file will not yet have actually been
  202.    created.  Therefore, there is no point in doing a status call or a file
  203.    update yet.  If you want the file that is going to be created to be on
  204.    hold so that it doesn't get processed by the Despooler until you release it,
  205.    then create an SP2.DAT record so indicating.  (Refer to the User's Guide
  206.    for instructions on how SP2.DAT functions.)
  207.  
  208. 2. Run your application.
  209.  
  210. 3. Perform an "obtain status about a spool file" function (8., above).  Point
  211.    ES:BX to the 33 bytes save area that you created in step 1.
  212.  
  213. 4. Perform the "update a spool file" function (9., above), changing the number
  214.    of copies.
  215.